using System;
using System.Threading.Tasks;

namespace Lazy.Captcha.Core.RateLimit
{
    /// <summary>
    /// 频率限制器接口
    /// </summary>
    public interface IRateLimiter
    {
        /// <summary>
        /// 检查是否允许请求
        /// </summary>
        /// <param name="key">限制键</param>
        /// <param name="windowSeconds">时间窗口（秒）</param>
        /// <param name="maxRequests">最大请求次数</param>
        /// <returns>是否允许请求</returns>
        bool IsAllowed(string key, int windowSeconds, int maxRequests);

        /// <summary>
        /// 异步检查是否允许请求
        /// </summary>
        /// <param name="key">限制键</param>
        /// <param name="windowSeconds">时间窗口（秒）</param>
        /// <param name="maxRequests">最大请求次数</param>
        /// <returns>是否允许请求</returns>
        Task<bool> IsAllowedAsync(string key, int windowSeconds, int maxRequests);

        /// <summary>
        /// 获取剩余请求次数
        /// </summary>
        /// <param name="key">限制键</param>
        /// <param name="windowSeconds">时间窗口（秒）</param>
        /// <param name="maxRequests">最大请求次数</param>
        /// <returns>剩余请求次数</returns>
        int GetRemainingRequests(string key, int windowSeconds, int maxRequests);

        /// <summary>
        /// 获取下次重置时间
        /// </summary>
        /// <param name="key">限制键</param>
        /// <param name="windowSeconds">时间窗口（秒）</param>
        /// <returns>下次重置时间</returns>
        DateTime? GetResetTime(string key, int windowSeconds);
    }
}
